home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / dviware / dtl / README < prev    next >
Text File  |  1995-02-28  |  7KB  |  150 lines
  1. README for DTL package - Wed 1 March 1995
  2. -----------------------------------------
  3. Author: Geoffrey Tobin <G.Tobin@ee.latrobe.edu.au>
  4. Version: 0.5.3
  5. CTAN Archive-path: dviware/dtl
  6. Brief Description:
  7.  DTL (DVI Text Language) files are equivalent to TeX's DVI files,
  8.  but are humanly readable, instead of binary.  Two programs are
  9.  provided to translate between DVI and DTL:  dv2dt, dt2dv.
  10.  In this release dt2dv warns if byte addresses or string lengths
  11.  recorded in a DTL file are incorrect, then overrides them.  This
  12.  makes DTL files editable.
  13. Keywords: dvi, TeX
  14. Includes:
  15.  Makefile  README  dt2dv.c  dtl.doc  dtl.h
  16.  dv2dt.c  dvi.doc  example.tex  tripvdu.tex
  17.  
  18. Motivation:
  19.  
  20.  When TeX has typeset a document, it writes its handiwork to a DVI
  21. file, for DVI processing software (such as viewers, printer drivers,
  22. dvidvi, and dvicopy) to read.
  23.  
  24. The file  dvi.doc  lists the DVI file commands, with their opcodes
  25. (byte values), nominal command names, arguments, and meanings.  For a
  26. detailed description of DVI file structure, see one of these:
  27. 1.  Donald E. Knuth's book _TeX: The Program_;
  28. 2.  The file tex.web, which contains source and documentation for TeX:
  29.         CTAN:  systems/knuth/tex/tex.web
  30. 3.  The source for Knuth's dvitype program:
  31.         CTAN:  systems/knuth/texware/dvitype.web
  32. 4.  Joachim Schrod's DVI drivers standard document, the relevant part
  33.     of which is at
  34.         CTAN:  dviware/driv-standard/level-0
  35.  
  36. Sometimes human beings are interested to see exactly what TeX has
  37. produced, for example when viewing or printing of the DVI file gives
  38. unexpected results.  However, a DVI file is a compact binary
  39. representation, so we need software to display its contents.
  40.  
  41. Binary file editors, when available, can show the DVI bytes, but not
  42. their meanings, except for the portions that represent embedded text.
  43. In particular, the command names are not shown, and the command
  44. boundaries are not respected.
  45.  
  46. By contrast, Knuth's dvitype program is designed as an example of a
  47. DVI driver.  However, dvitype is inconvenient for studying the DVI
  48. file alone, for the following reasons:
  49. 1.  Being a DVI driver, dvitype endeavors to read the TFM font metric
  50. files referenced in the DVI file.  If a TFM file is absent, dvitype
  51. quits with an error message.
  52. 2.  When it starts, it prompts the user interactively for each of a
  53. series of options.
  54. 3.  Even the least verbose option gives masses of information that is
  55. not contained in the DVI file, coming instead from a combination of
  56. the data in the DVI file and TFM files.
  57. 4.  It does NOT show the DVI information in a way that accurately
  58. reflects the structure of the DVI file.
  59. 5.  Its output, if redirected to a file, produces a very large file.
  60. 6.  There is no automated procedure for converting the output of
  61. dvitype back to a DVI file, and doing it by hand is totally
  62. unreasonable.
  63.  
  64. The first disadvantage is a killer if a TFM file is absent.
  65. Disadvantages two to four make dvitype very inconvenient for studying
  66. a DVI file.  The fifth problem makes dvitype's output tedious,
  67. disk-hungry (so one deletes it almost immediately), and unsuitable for
  68. file transfer.
  69.  
  70. The sixth disadvantage of dvitype is important to those people who are
  71. interested in editing DVI files.  Since the DVI files refer explicitly
  72. to their own internal byte addresses, it's very easy to mess up a DVI
  73. file if one were to try to edit it directly, even apart from the problem
  74. of how to recognise a command.
  75.  
  76. So an exact, concise, textual representation of a DVI file is needed,
  77. but dvitype does not produce one.
  78.  
  79. Resolution:
  80.  
  81.  Therefore, working from Joachim Schrod's description, I designed DTL
  82. and its conversion programs dv2dt (DVI -> DTL) and dt2dv (DTL -> DVI),
  83. which are provided as C sources:
  84.  
  85.     dtl.h
  86.     dv2dt.c
  87.     dt2dv.c
  88.  
  89. Although I was motivated by the TFM <-> PL conversion provided by
  90. Knuth's tftopl and pltotf programs, I deliberately designed DTL to be
  91. a much more concise and literal translation than the `property list'
  92. structure exemplified by PL.  The result is that a DTL file is
  93. typically three times the size of its equivalent DVI file.  The
  94. document  dtl.doc  lists the correspondence between the DTL command
  95. names and the (nominal) DVI command names.
  96.  
  97. A clear advantage of an exact two-way conversion is that we can check
  98. (and prove) whether the converters worked truly on a given DVI file.
  99. The provided plain TeX files:
  100.     example.tex
  101.     tripvdu.tex
  102. can be used to test whether the compiled programs are behaving
  103. sensibly.  Whereas  example.tex  is a simple document that uses a
  104. variety of plain TeX commands,  tripvdu.tex  provides a kind of
  105. `trip test' for DVI processor programs.  Both documents are taken,
  106. with permission, from Andrew K. Trevorrow's dvitovdu (alias dvi2vdu)
  107. distribution (and are also part of the dvgt viewer distribution).
  108.  
  109. The  Makefile  might have to be edited for your site, as it assumes
  110. gcc  for your C compiler.  Makefile compiles dv2dt and dt2dv, then
  111. runs  tex  on example.tex and tripvdu.tex, and also converts the
  112. resulting DVI files to DTL files, back to DVI files (with a change
  113. of name), then back again to DTL files, so that the results can be
  114. compared using a textual differencing program.  (Many computer systems
  115. have such a program; on unix, as assumed by Makefile, this is named
  116. `diff';  ms-dos has one named `comp'.)  This should produce a
  117. zero-length  .dif  file for each document, proving that the two DTL
  118. files are identical.
  119.  
  120. A keen tester might also use a binary difference program on the DVI
  121. files, to check that they are identical, as they need to be.  (Many
  122. unix systems have a binary differencer named `bdiff'.)
  123.  
  124. Note:
  125.  
  126.  In representing numeric quantities, I have mostly opted to use
  127. decimal notation, as this is how most of us are trained to think.
  128. However, for the checksums in the `fd' (font definition) commands, I
  129. chose octal notation, as this is used for checksums in Knuth's PL
  130. files, against which DVI files must be compared when a DVI driver
  131. loads a font.
  132.  
  133. Caveat:
  134.  
  135.  Although the current version of dt2dv allows DTL files to be edited,
  136. because it overrides byte addresses, nonetheless one must be careful
  137. when editing font path names, because they are preceded by two length
  138. specifications: the first for the font `area' (font directory) and the
  139. second for the font file's name.  Often the area will be empty
  140. (especially if the DVI file is to be portable), but not necessarily.
  141. So if users edit a font path name in a DTL file, then they must count
  142. its new area- and file- name substring lengths, and update them
  143. correctly in the DTL file, otherwise the DVI file produced will be
  144. seriously wrong.
  145.  
  146. dt2dv currently needs the integer, given before each string, to contain
  147. its accurate length.  So users who edit a text string must
  148.  
  149. End of README
  150.